TCP Provider

Raw TCP socket communication for UTCP

The TCP provider enables UTCP to interact directly with services over raw TCP sockets, allowing for low-level network communication with minimal protocol overhead. This provider is ideal for high-performance applications or legacy systems using custom TCP protocols.

Configuration

TCP providers are configured using the following JSON structure:

{
  "name": "tcp_service",
  "provider_type": "tcp",
  "host": "api.example.com",
  "port": 9000,
  "timeout": 30000,
  "keep_alive": false,
  "encoding": "utf-8"
}

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier for the provider
`provider_type`	Yes	Must be set to `"tcp"`
`host`	Yes	Hostname or IP address of the TCP server
`port`	Yes	Port number of the TCP server
`timeout`	No	Connection and operation timeout in milliseconds (default: `30000`)
`keep_alive`	No	Whether to keep connections alive between requests (default: `false`)
`encoding`	No	Text encoding for string data (default: `"utf-8"`)
`buffer_size`	No	Buffer size for reading data (default: `4096`)

Protocol Considerations

Since TCP is a raw transport protocol, implementations need to define:

Message Framing

How to determine message boundaries (length prefixes, delimiters, fixed-size messages)

Data Serialization

Format for sending structured data (JSON, Protocol Buffers, custom binary formats)

Error Handling

How errors are communicated within the protocol

Tool Discovery

Since raw TCP doesn't support standardized discovery protocols, UTCP tools using TCP providers typically rely on:

Static Definition: Tool definitions provided in a separate JSON file
Companion HTTP Endpoint: A companion HTTP endpoint at /utcp
Custom Protocol: A custom discovery protocol over the TCP connection

{
  "name": "tcp_service",
  "provider_type": "tcp",
  "host": "api.example.com",
  "port": 9000,
  "discovery_url": "https://api.example.com/utcp"
}

Examples

Time Server

{
  "name": "time_server",
  "provider_type": "tcp",
  "host": "time.example.com",
  "port": 13,
  "timeout": 5000,
  "encoding": "ascii"
}

Custom Protocol Service

{
  "name": "custom_service",
  "provider_type": "tcp",
  "host": "service.example.com",
  "port": 8080,
  "keep_alive": true,
  "buffer_size": 8192,
  "timeout": 60000
}

Best Practices

Connection Management

Implement connection pooling for frequently used services
Use keep-alive for persistent connections when appropriate
Implement robust reconnection logic with exponential backoff
Set appropriate timeouts for both connection and operations

Protocol Design

Clearly define message framing and boundaries
Use consistent data serialization formats
Implement proper error codes and handling
Consider endianness for binary protocols

Security

Validate all incoming data against expected schemas
Implement proper authentication mechanisms
Use TLS/SSL for encrypted communication when needed
Protect against buffer overflow attacks